home *** CD-ROM | disk | FTP | other *** search
/ Chip: 2005 Utilities / CHIP Utilities 2005 / CHIP Utilities 2005.iso / dosapps / dosnavig / DOC / ENGLISH / DNOSP.TXT < prev    next >
Encoding:
Text File  |  2003-03-23  |  14.3 KB  |  242 lines
  1. ==============================================================================
  2.                       Dos Navigator Open Source Project
  3.             Based on Dos Navigator (C) 1991-1999 RIT Research Labs
  4. ==============================================================================
  5.  
  6.     Last revision date: Wednesday November 28 2001
  7.  
  8.                               Table of Contents
  9.  
  10.  1. General issues
  11.  2. Creating patches
  12.  3. Programming style
  13.  4. Applying patches
  14.  5. [CHANGED] New DN versions distribution
  15.  6. [CHANGED] Project coordinators
  16.  
  17.                               1. General issues
  18.  
  19.     Dos  Navigator  Open  Source  Project  is dedicated for development of the
  20.  popular  file  shell Dos Navigator (DN) through collective efforts of an open
  21.  group of programmers.
  22.     Programmers participating in the project do not carry out material profit,
  23.  but everyone is mentioned in the authors list of every consequential version.
  24.  The  project  participants  should  be aware that the source text they create
  25.  will  be  distributed publicly and is subject for free usage and modification
  26.  while preserving the author's copyrights.
  27.     Third  party  companies  and programmer groups can create products derived
  28.  from Dos Navigator Open Source while maintaining the following conditions:
  29.      1. Keeping all the project participants' and coordinators' names in the
  30.         About box and authors.txt file included with all new versions
  31.      2. Keeping dnosp.txt and authors.txt files in the distribution package
  32.      3. Including in the About box and in the text documentation the line
  33.         "Based on Dos Navigator Open Source"
  34.     Not  meeting  these  conditions  is  considered  a  violation  of  project
  35.  participants' copyrights.
  36.     The  collective  of  programmers  is  open, and no kind of registration is
  37.  required to enter or exit the project.
  38.     The  project  coordinator  accumulates  the  changes  made  by the project
  39.  participants,  compiles  new  versions  of  DN,  tests  the  new features for
  40.  collective functioning and periodically releases new versions.
  41.     All the changes the project participants make they send to the coordinator
  42.  on  the  source text level. The means of communication to the coordinator are
  43.  listed at the bottom of this document.
  44.     The coordinator is elected. In case of impossibility or the lack of desire
  45.  from  the  effective  coordinator  to continue his job, expressed either in a
  46.  public  message or in failing to communicate to project participants for more
  47.  than  a  month,  failing  to release new DN version for more than a month, or
  48.  failing  to communicate for more than two weeks without an explicit temporary
  49.  transfer  of  the  coordinatorship to another project participant, or also in
  50.  case  if  most  of  the  project  participants publicly express that they are
  51.  unsatisfied  by  the coordinator's work since he or she was last elected, the
  52.  coordinator  is re-elected. Anybody who publicly expresses so can participate
  53.  as  a candidate, and the coordinator is elected by a simple majority of votes
  54.  by the RU.SHELL.DN subscribers.
  55.     The  discussion  of  project  details  and the collaborative communication
  56.  between  the  programmers  that  is  of  interest  to a significant number of
  57.  subscribers  is  carried  out  in  the  RU.SHELL.DN  Fidonet  echo area. This
  58.  document  is  posted  to  RU.SHELL.DN  every  month or immediately when it is
  59.  modified.  The modifications are marked with [NEW] and [CHANGED] in the table
  60.  of contents.
  61.     Those  who  have  the  technical ability are recommended to post copies of
  62.  this  document to the appropriate Fidonet areas (shells, programming) as well
  63.  as to other computer networks.
  64.     Localization  is welcome. Localization for a national language can be done
  65.  by creating a new set of language resources (and not by derival of a separate
  66.  DN  version).  If  you  have  decided to start DN localization for a specific
  67.  language,  please communicate to the coordinator (see bottom of this document
  68.  for coordinates).
  69.     Translation of this document to other languages is welcome.
  70.  
  71.                              2. Creating patches
  72.  
  73.     The preferred form of submitting source code modifications is a patch. The
  74.  patch method is widely utilized in a number of large projects. For an example
  75.  see  the  Linux  operating  system  kernel, whose source text is available at
  76.  ftp://www.kernel.ru.org/pub/Linux/kernel/.
  77.     A  patch  is  the  text resulting from the comparison of two text files or
  78.  directories  with files. Patches are saved in such form that permits applying
  79.  a patch to one of those files (or directories) making it same with the other.
  80.     In  our  project  a  patch is a result of comparison between two DN source
  81.  code directories, first being the current (base) version of DN and the second
  82.  being the same version with some kind of modification made.
  83.     The  diff  utility is used to create patches. It was ported from UNIX and,
  84.  as  available  now,  works  in Win32 console mode and in 32-bit DOS protected
  85.  mode  -  DPMI (DOS/4GW). Please make sure that you have the diff port version
  86.  PORT.2  or  higher,  since  the  previous port could behave incorrectly. Full
  87.  description  of diff as well as its source code is available from the project
  88.  coordinator.
  89.     To compare two directories, the following command should be used:
  90.         diff -urN base_version_dir modified_version_dir >file.patch
  91.     It  is  considered  that  two  subdirectories of the current directory are
  92.  compared. The description of the -u, -r and -N options (which can be combined
  93.  in a single option) can be found in the built-in help text:
  94.         diff --help |more
  95.     All the options are case sensitive (this is the UNIX standard).
  96.     It is recommended to name patch files as shown:
  97.         dn-base_version-application_subject.patch
  98.     For example:
  99.         dn-1-51-phonebook-export.patch
  100.     Modification  can  span multiple files, include new (added) files and text
  101.  files other than pas files (resource definition files, etc).
  102.     It is not recommended to combine in one patch different modifications that
  103.  are not related to each other.
  104.     Please  note  the  patch  description template, which is recommended to be
  105.  used  to write patch description files. The name format recommended for these
  106.  files is:
  107.         dn-base_version-application_subject.info
  108.     Please  refrain  from  using space characters as well as more than one dot
  109.  character  in  the  names  of  patch file itself and its description file, as
  110.  these can cause problems under certain operating systems.
  111.     Both files should be packed together with an archiver supporting long file
  112.  names  (WinZip  is  recommended  -  http://www.winzip.com/),  and the archive
  113.  should be given a short name to avoid various mailing problems. Such archives
  114.  are  rather  compact,  making  it possible to send them UU-encoded in netmail
  115.  messages.
  116.     It  is  recommended  to  start  names  for this archives with the last two
  117.  digits  of the base version number. For example, 01dsvcen.zip is a reasonable
  118.  name for an archive containing a patch based on DN 1.51.01 sources.
  119.     Those project participants who do not have the technical ability to create
  120.  archives  in  accordance  to  the  recommendations  stated  above  can create
  121.  archives  in  the  way they find it possible and convenient, but in this case
  122.  the archives should be sent to the coordinator as private mail.
  123.  
  124.                              3. Programming style
  125.  
  126.     Due  to a rather large number of programmers participating in the project,
  127.  it   is  desirable  to  follow  the  recommendations  stated  below  to  make
  128.  collaboration easier.
  129.     The  project  is international at the present time, so all comments in the
  130.  source text should be written in English.
  131.     When  a  modification of language resources is necessary, change resources
  132.  only  for  the language you know, and include a note in the patch description
  133.  file  stating  for  what languages the modification was made. The coordinator
  134.  will   make   the  modifications  for  the  other  languages  himself  or  by
  135.  communicating to the native speakers of those languages.
  136.     All  the  messages, text, dialogs and other elements of the user interface
  137.  should  be  localizable.  This  means that these items should be based on the
  138.  language  resource contents. An exclusion can be made only for a special kind
  139.  of  fatal  error  messages  and  some  other occasions when it is technically
  140.  impossible to access the language resources.
  141.     If several lines are changed or added, these lines should be marked with a
  142.  comment  with the programmer's name or nickname, for example, { X-Man }. When
  143.  a  large  group of lines is added (like a whole function), its top and bottom
  144.  should be marked with such comments, each spanning a whole separate line.
  145.     When  adding a constant to a group of numeric constants (like cmXXXX), the
  146.  first  unoccupied value is recommended to be used for the new constant rather
  147.  than shifting values for a range of other constants.
  148.     If  a  feature  is  introduced  in  a  patch,  and  this feature is rather
  149.  standalone in the sense that it can be easily removed without impairing other
  150.  functionality,  this  feature  should  be  made  optional  at compile time by
  151.  surrounding   the  new  code  with  conditional  compilation  directives  and
  152.  including  a conditional define directive for the new feature in stdefine.inc
  153.  file.
  154.     When  adding  features that are based on some DOS virtual machine features
  155.  or services under a particular operating system, a service availability check
  156.  or  an  operating system check should be performed before actually using such
  157.  services  or  features.  For  the  operating  system check the opSys variable
  158.  should  be  analyzed. The opSys variable is defined in the Advance unit along
  159.  with  a  set  of  numeric constants representing different operating systems.
  160.  Values  of  the  constants  can  be  bitwisely  combined,  meaning  that  the
  161.  environment   provides  functionality  of  more  than  one  operating  system
  162.  (possible  under  some emulators). Feel free to add new constants to that set
  163.  and appropriately expanding the functionality of the CheckOS procedure.
  164.     Please  do  not include history.txt, authors.txt and the About box updates
  165.  in your patches. These changes are made by the project coordinator.
  166.  
  167.                              4. Applying patches
  168.  
  169.     The patch utility is complementary to diff and is used to apply patches.
  170.     To apply a patch, the following command should be used:
  171.         patch -p1 <file.patch
  172.         (assuming you have the ported patch tool version PORT.2 or higher)
  173.     It  is  considered  that  the  current directory is the directory with the
  174.  current DN version (the directory name is not significant).
  175.     The  version  of source code subject to patch application does not have to
  176.  be  identical  to  the  base  version.  Practically this means that the patch
  177.  utility has some amount of tolerance to the source code changes and different
  178.  patches  can  be  applied  to  the  same  sources  independently.  But  since
  179.  accumulation of sources text changes can lead to exhausting the patch utility
  180.  tolerance,  all patches should be created basing on the latest source version
  181.  available.
  182.     The patch utility automatically detects the situation when the patch being
  183.  applied  has  already  been  applied  to  the  source code. In this case, the
  184.  utility  works  in  reversed  mode,  removing the patch without affecting the
  185.  others.
  186.  
  187.                        5. New DN versions distribution
  188.  
  189.     New  DN versions are distributed by the project coordinator. The NAVIGATOR
  190.  fileecho  serves for this purpose. The new versions are also available at the
  191.  following Internet addresses:
  192.         http://www.dnosp.ru
  193.         http://dn.traktir.ru
  194.     Each new version is released as four packages:
  195.         DN<version>S.RAR - source code (mainly for the project participants)
  196.         DN<version>B.RAR - binary distribution for DOS  real-mode  environment
  197.                            (for the end user)
  198.         DN<version>D.RAR - binary distribution for DOS protected-mode
  199.                            environment - DPMI (for the end user)
  200.         DN<version>P.RAR - a set of extra files for the end user
  201.     The  fourth  packet  contains screensavers, xlat tables, Windows icons and
  202.  examples of text configuration files. This package is not released with every
  203.  version but only when an update is necessary.
  204.     All  four  packets include the authors list (authors.txt) and the revision
  205.  history  (history.txt)  as well as this document (dnosp.txt). The source code
  206.  package  also  has  the patch description template (template.txt) inside. The
  207.  revision  history  for  the  period  of RIT Labs developing and support of DN
  208.  along  with  the  RIT Labs copyright information is placed in a separate file
  209.  (ritlabs.txt).
  210.     When  needed, other packages may be released as well, such as localization
  211.  sets for national languages.
  212.     With each new version, two more files are released:
  213.         PATCH<minor version>.RAR - patch collection since last release
  214.         <old minor version>TO<new minor version>.RAR - cumulative update patch
  215.     Beta  versions  may  be  released  when  necessary.  A  beta  version is a
  216.  supplementary  release  intended  solely  for  beta-testing purposes, not for
  217.  general usage. A person who is going to do beta-testing is encouraged to mail
  218.  the  project  coordinator  and  give information about which version would be
  219.  tested,  and in what hardware and software environment (regardless of whether
  220.  he or she did beta-testing of prior versions).
  221.     While  in  beta-state,  new  beta-versions are released each time when two
  222.  weeks  elapse  since  the  last  beta-version  was released and not less than
  223.  twenty new patches were installed, or when four weeks elapse.
  224.  
  225.                            6. Project coordinators
  226.  
  227.     First coordinator:
  228.         Max Vasilyev
  229.         2:5057/33.36@fidonet
  230.         piwamoto(at)pisem.net
  231.         http://www.sama.ru/~piwamoto/
  232.         http://dn.traktir.ru/
  233.     Second coordinator:
  234.         Eugeny Zvyagintzev
  235.         2:5004/18.60@fidonet
  236.         dn_osp(at)pisem.net
  237.         http://dnosp.nm.ru
  238.     Third coordinator:
  239.         check out our www pages and RU.SHELL.DN Fidonet echo area
  240.  
  241. ==============================================================================
  242.